========================================================
  FROM THE SKIES — User Manual
  FIU KFSCIS Capstone II | Spring 2026
========================================================

OVERVIEW
--------
FromTheSkies adds a one-time alien invasion event to your Minecraft world.
An alien civilization called the Breem sends a meteor to the Overworld.
Once it lands, the surface slowly becomes infected — spreading block by block,
converting grass, dirt, and trees into alien Breem variants, and eventually
transforming the biome itself. You can stop the invasion by finding and
destroying the Alien Core.

========================================================
1. THE INVASION — HOW IT WORKS
========================================================

Phase 1 — DORMANT
  The mod is active but waiting. Nothing happens yet.
  The system monitors how many Overworld chunks you have explored.
  Once you cross the configured threshold (default: 512 chunks),
  the invasion arms itself automatically.

Phase 2 — ARMED
  The invasion is armed. A meteor is scheduled to land between
  1 and 3 in-game days from this point.

Phase 3 — ACTIVE
  The meteor lands. An Alien Core block appears at the landing site.
  From this point, the infection begins spreading outward:
    - Grass blocks convert to Breem Grass (yellow-green).
    - Dirt blocks adjacent to infected grass convert to Breem Dirt.
    - Trees whose base is touched by the infection convert entirely —
      logs become Breem Logs and leaves become Breem Leaves.
    - Once 35% of a chunk's surface is infected, the chunk's biome
      permanently converts to the alien_overgrowth biome.

Phase 4 — STOPPED
  The invasion halts when the Alien Core is destroyed.
  Already-infected blocks and converted biomes remain permanently changed.
  No new spread will occur.

========================================================
2. THE BREEM MOBS
========================================================

Breem are the alien inhabitants of the infected biome. They spawn
naturally in alien_overgrowth chunks and come in four variants:

  Villager  — Passive trader variant.
  Soldier   — Combat variant, attacks on sight.
  Brute     — Heavy combat variant, high health and damage.
  Shaman    — Support variant.

DIAMOND DIPLOMACY
  Breem are neutral toward players who are holding a diamond
  or wearing any piece of diamond armor.

  To trade with a Breem:
    1. Hold a diamond or wear diamond armor.
    2. Right-click a Breem mob.
    3. The Breem will inspect the diamond (40-tick animation).
    4. You will receive a random reward:
       Ender Pearl, Obsidian, String, Quartz,
       Fire Charge, or Spectral Arrow.

  If you attack a Breem, nearby Breem will be alerted
  and become hostile toward you.

========================================================
3. BREEM TREES
========================================================

Breem Saplings can be obtained from infected areas.
Plant them on Breem Dirt or Breem Grass to grow a Breem tree.
Use Bonemeal on a planted sapling to grow it instantly.

Breem trees feature:
  - Breem Log trunk (dark alien wood)
  - Breem Leaf canopy (orange leaves)
  - Stripped Breem Log (use an axe on a Breem Log)

========================================================
4. THE ALIEN CORE
========================================================

The Alien Core is the source of the invasion. It appears at the
meteor landing site when the invasion becomes active.

  - It is indestructible in Survival without the correct tool.
  - Destroying it permanently stops the spread.
  - Breaking the core drops diamonds as a reward.

To find the core use the admin command:
  /fts takeover status
And look for the core=X,Y,Z coordinates in the output.

========================================================
5. CONFIGURATION
========================================================

On first launch, a config file is created at:
  .minecraft\config\fromtheskiesmcmod-common.toml

Key settings you can adjust:

  enabled = true
    Master switch. Set to false to disable all invasion logic.

  minGeneratedChunksSeen = 512
    How many chunks must be explored before the invasion arms.
    Lower this for faster starts in testing.

  meteorMinTicks = 24000
  meteorMaxTicks = 72000
    Min and max delay (in ticks) between arming and meteor landing.
    24000 ticks = 1 in-game day.

  spreadIntervalTicks = 20
    How often the spread engine runs (20 = once per second).

  chunkBiomeFlipThreshold = 0.35
    What fraction of a chunk must be infected before the biome converts.

========================================================
6. ADMIN COMMANDS (Requires Operator Level 2)
========================================================

These commands are intended for server admins and testing.
In singleplayer, use /op [your username] first.

  /fts takeover status
    Shows the current invasion state, core location, infected block
    count, converted chunk count, and other live data.

  /fts takeover force_arm
    Immediately arms the invasion, skipping the chunk threshold.

  /fts takeover force_meteor
    Immediately fires the meteor, skipping the timer.

  /fts takeover step <ticks>
    Simulates the given number of spread ticks instantly.
    Example: /fts takeover step 1000

  /fts takeover stop
    Immediately stops the invasion as if the core was broken.

QUICK DEMO SEQUENCE
  /fts takeover force_arm
  /fts takeover force_meteor
  /fts takeover status         (find the core coordinates)
  /tp @s X Y Z                 (teleport to the core)
  /fts takeover step 2000      (fast-forward the spread)

========================================================
